Update ansible doc formats #71070
Update ansible doc formats #71070
Conversation
ansibot
added
affects_2.11
bug
|
The test |
ansibot
added
needs_revision
|
Are |
samdoran
removed
the
needs_triage
abadger
force-pushed
the
update-ansible-doc-formats
branch
from
390245a
to
a1413d7
Compare
ansibot
added
core_review
|
Unit test added and some bugs that I found while adding tests cases fixed. I'm working on adding documentation that @samccann asked for now as these all come from the code that's currently building the docsite. |
abadger
force-pushed
the
update-ansible-doc-formats
branch
from
a1413d7
to
43c15d7
Compare
ansibot
added
docs
|
The test |
ansibot
added
needs_revision
* Move tty_ify() and supporting attributes to the DocCLI class as that's the only thing using it. * Add unittest for the code. * Fix a bug where the substitution macros can be detected when they are a part of another word. * Add support for L(), R(), and HORIZONTALLINE which were added to the website docs many years ago.
abadger
force-pushed
the
update-ansible-doc-formats
branch
from
43c15d7
to
ee78a08
Compare
ansibot
added
core_review
|
@mattclay can you look at the test failures here? It looks to me like it's a false positive. The tests have completed successfully but something (I can't tell if it's in pytest or in ansible-test) is comparing a list of the tests that are supposed to have run and it finds the lists different. However, the difference is actually just in the order of the tests, not in the tests or the results. I'm not sure if there's something I should do (Maybe sorting of the dictionary keys?) or if this is a bug in the test framework that should be solved in the framework. |
Co-authored-by: Matt Clay <matt@mystile.com>
ansibot
added
core_review
| There are also some macros which do not create links but we use them to display certain types of | ||
| content in a uniform way: | ||
|
|
||
| * ``I()`` for option names. For example: ``Required if I(state=present).`` This is italicized in |
There was a problem hiding this comment.
I thought parameters should use C() so they are formatted as inline code. That's just my personal preference, though.
There was a problem hiding this comment.
Uh oh, lots of things for you to correct, then ;-)
| def tty_ify(cls, text): | ||
|
|
||
| t = cls._ITALIC.sub(r"`\1'", text) # I(word) => `word' | ||
| t = cls._BOLD.sub(r"*\1*", t) # B(word) => *word* |
There was a problem hiding this comment.
This may not matter because something else may handle the RST --> HTML conversion, but for in RST, **word** is the syntax for bold while *word* is the syntax for italic. If this is only for the display of ansible-doc, this should be fine. But it'd be surprising if B(word) ended up being italic in the final HTML.
There was a problem hiding this comment.
rst and html (for building the web docs) are handled by rst_ify and html_ify from this code: https://github.com/ansible-community/antsibull/blob/main/antsibull/jinja2/filters.py
The code in this PR is only for ansible-doc to output to the screen.
This split is why I added the note that the code in both places needs to be changed if new macros are added.
There was a problem hiding this comment.
Ah, ok. I figured they were separate and this was only for ansible-doc output. I just wanted to make sure.
There was a problem hiding this comment.
Fun times with cross project relationships. 😁
* Fix tty_ify bugs and refactor * Move tty_ify() and supporting attributes to the DocCLI class as that's the only thing using it. * Add unittest for the code. * Fix a bug where the substitution macros can be detected when they are a part of another word. * Add support for L(), R(), and HORIZONTALLINE which were added to the website docs many years ago. * Update test/units/cli/test_doc.py Co-authored-by: Matt Clay <matt@mystile.com> Co-authored-by: Matt Clay <matt@mystile.com> (cherry picked from commit fb144c4) Co-authored-by: Toshio Kuratomi <a.badger@gmail.com>
* Fix tty_ify bugs and refactor * Move tty_ify() and supporting attributes to the DocCLI class as that's the only thing using it. * Add unittest for the code. * Fix a bug where the substitution macros can be detected when they are a part of another word. * Add support for L(), R(), and HORIZONTALLINE which were added to the website docs many years ago. * Update test/units/cli/test_doc.py Co-authored-by: Matt Clay <matt@mystile.com> Co-authored-by: Matt Clay <matt@mystile.com>
* Fix tty_ify bugs and refactor * Move tty_ify() and supporting attributes to the DocCLI class as that's the only thing using it. * Add unittest for the code. * Fix a bug where the substitution macros can be detected when they are a part of another word. * Add support for L(), R(), and HORIZONTALLINE which were added to the website docs many years ago. * Update test/units/cli/test_doc.py Co-authored-by: Matt Clay <matt@mystile.com> Co-authored-by: Matt Clay <matt@mystile.com> (cherry picked from commit fb144c4) Co-authored-by: Toshio Kuratomi <a.badger@gmail.com>
SUMMARY
The ansible specific formats that ansible-doc knows about needed to be updated for things that were added to the website build.
ISSUE TYPE
COMPONENT NAME
ADDITIONAL INFORMATION
@samdoran